/***************************************************************
*  Copyright (c) 2007 by GroupMe! Team (www.groupme.net)
*  All rights reserved.
*
*  This file is part of the GroupMe! Project. Source code of 
*  this project is closed and redistribution of this code is
*  prohibited. 
*  
*  Contact: http://www.groupme.net
*
*  This copyright notice MUST APPEAR in all copies of the file!
***************************************************************/
package net.groupme.search.strategy;

import java.util.Calendar;
import java.util.List;

import net.groupme.model.Group;
import net.groupme.model.Resource;
import net.groupme.model.User;
import net.groupme.search.strategy.model.WeightedTag;

/**
 * created on Jul 6, 2007
 * 
 * This interface defines methods for searching for tags.
 * 
 * @author Fabian Abel, <a href="mailto:abel@l3s.de">abel@l3s.de</a>
 * @author last edited by: $Author: fabian $
 * 
 * @version $Revision: 1.5 $ $Date: 2009-01-20 18:47:45 $
 */
public interface TagSearchStrategy {

	/**
	 * This method returns an ordered list of {@link WeightedTag} instances. Ordering is done according
	 * to the number of occurences in the given period. Such a list builds the base for <i>Tag Clouds</i>.
	 * 
	 * @param beginOfPeriod start of period. If this is <code>null</code> then all tag occurences that have 
	 * a date lesser than <i>endOfPeriod</i> are considered. 
	 * @param endOfPeriod end of period. If this is <code>null</code> then all tag occurences that have 
	 * a date greater than <i>beginOfPeriod</i> are considered. 
	 * @param user the user who tagged the resources. If this is <code>null</code> then tag occurences of all 
	 * users are considerd. 
	 * @param topK to specify the maximum number of tags that are contained in the tag cloud. If <code>topK</code> = 50 then the 50 most
	 * important tags are returned (50 most popular tags). If <code>topK == null</code> then all tags will be returned (this may take very long).
	 * @return an ordered list of {@link WeightedTag} instances according to the number of occurrences in the specified period of time
	 */
	public List<WeightedTag> getTagCloud(Calendar beginOfPeriod, Calendar endOfPeriod, User user, Integer topK);
	
	/**
	 * This method returns the tag cloud of a group which is an ordered list of {@link WeightedTag} instances. 
	 * Ordering is done according to the number of occurrences in the given period within the group. 
	 *  
	 * @param group the group about which the tag cloud should be 
	 * @param topK to specify the maximum number of tags that are contained in the tag cloud. If <code>topK</code> = 50 then the 50 most
	 * important tags are returned (50 most popular tags). If <code>topK == null</code> then all tags will be returned (this may take very long).
	 * @return an ordered list of {@link WeightedTag} instances according to the number of occurrences in the specified period of time
	 */
	public List<WeightedTag> getTagCloud(Group group, Integer topK);
	
	
	/**
	 * This method returns the tag cloud of a resource which is an ordered list of {@link WeightedTag} instances. 
	 * Ordering is done according to the number of occurrences. 
	 *  
	 * @param resource the group about which the tag cloud should be 
	 * @param topK to specify the maximum number of tags that are contained in the tag cloud. If <code>topK</code> = 50 then the 50 most
	 * important tags are returned (50 most popular tags). If <code>topK == null</code> then all tags will be returned (this may take very long).
	 * @return an ordered list of {@link WeightedTag} instances according to the number of occurrences
	 */
	public List<WeightedTag> getTagCloud(Resource resource, Integer topK);
}
